Developer CD Series 1998 May: Tool Chest/Dev.CD May 98 TC.toast/Tool Chest/Testing & Debugging/Mac OS Development Toolkit/Automation Essentials 2.3.0/Host Automation Folder/Clouseau libs/Clouseau.Lib

Text File | 1998-03-19 | 92.3 KB | 2,613 lines | [TEXT/MPS ]

#########################################################################
#########################################################################
##                     Copyright © Apple Computer, Inc. 1990-1997
##                                All rights reserved
#########################################################################
#########################################################################
#
#    Library:        Clouseau.lib
#
#    Version:        2.1.4
#
#    Description:    Tasks that handle generic operations for high level
#                    tests.  All tasks return true if executed successfully,
#                    or false if an error occurs.
#
#    Contains:
#        await_presence()
#        await_absence()
#        balloon_await_presence()
#        type_keys()
#        select_descriptor()
#        select_menuitem()
#        move_mouse()
#        select_popup()
#        twitch()
#        select_volume()
#        find()
#        close_all_windows()
#        relocate_window()
#        dismiss_dialog()
#        select_window()
#        close_window()
#        key_eq()
#        find()
#        use_7_0_find()
#        abort_script()
#        AwaitText()
#        LocateText()
#        SetTextOptions()
#        GetTextOptions()
#        ValidateTextOptions()
#
#    History:
#        Some of these tasks were originally found in 007, written by EH
#        and Alan Liu.  Some have had minor changes, many have had major changes. Some
#        still use the names of their predecessors but are entirely rewritten.
#        Date:        By:            Changes:
#        5/92        Jason Marsh    Clouseau 1.0 creation
#        09/27/96    SBR/MSO/BRL    Updated copyright header
#                                Use SPEC exception handling method (ExceptionHandling.lib)
#        09/27/96    MSO            Added command and shift modifier
#                                Used key_eq modifier 6 to improve chances of getting 7.0 find
#        01/21/97    SBR            Deleted older exception code and comments.
#        03/20/97    SBR            Added 'center of rect' action to move_mouse.
#        04/07/97    SBR            Added wait() in await_presence/_absence for CHAT.
#        04/10/97    SBR            Added AwaitText(), LocateText(), SetTextOptions(),
#                                GetTextOptions(), ValidateTextOptions().
#        04/14/97      SBR            Added 'relToBounds' action to move_mouse.
#        05/15/97      SBR            Added FindFile() (moved in from LaunchQuits.lib).
#
#########################################################################
#########################################################################

Libraries
    "ExceptionHandling.lib"
    ,"Report.lib"
    ,"VUAid.lib"
    ;

#########################################################################
#    task        await_presence(feature_desc, time_limit, persistence, exact, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Wait for the feature with descriptor {feature_desc} to
#                    appear. If more than {time_limit} seconds pass, then
#                    return a false (error) result. If the feature is found,
#                    return a true result. If a non-zero {persistence} is
#                    specified, wait for the feature to be present for
#                    {persistence} seconds.  Use this library call instead
#                    of just wait() whenever possible because it's more robust.
#    Parameters:        feature_desc:    descriptor of thing to look for
#                    time_limit:        how long to wait in seconds
#                    persistence:    how long to ensure that the object
#                                    stays around.
#                    exact:            whether to perform an EXACT match
#                    v_level:        verbosity level for log output
#                                    Pass a v_level of 6 to silence errors
#                                    and not have them add up for the test summary
#    Returns:        success:    true
#                    failure:    false
#    Examples:        if (await_presence([statictext t: "No matching items were found."], 20) = error)
#                            #Wait up to 20 seconds for a dialog that says
#                            # "No matching items were found." to appear.
#                      return(incomplete);
#                             #If it does not appear, then return 'incomplete'.
#                    else    #otherwise call the task  "Open_Object"
#                           Open_Object('My Folder');
#    Assumptions:    We assume that {persistence} will be less than 3600
#                    (one hour) and that the {time_limit} will be less than
#                    86400 (a day).
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90 Alan Liu        Creation as part of ApplicationLib.vu for 007
#        3/4/92  Jason Marsh        Incorporation into Clouseau.Lib.
#        06/12/93    SBR            Modified to use Errors.lib
#        12/15/93    JDL            Corrected return information in the description
#                                area of the header
#        05/25/94    SBR            Modified to use _MatchBoolean instead of _Match
#        06/07/94    SBR            Modified to use timed_out() instead of timer()
#        04/07/97    SBR            Added wait() to reduce network traffic for CHAT.
#########################################################################
task    await_presence(feature_desc, time_limit := 10, persistence := 0,
            exact := true, v_level := 5)
begin
    wait_end := get_end_time(time_limit);    # Reset the time limit timer
    persist_end := 0;                        # Reset the persistence timer

    while true
    begin
        found := _MatchBoolean(feature_desc, exact);
        if not found
            persist_end := 0;                # No match; reset persistence
        else
        begin
            if not persistence
                return true;
            else
            begin
                if not persist_end
                    persist_end := get_end_time(persistence);
                if timed_out(persist_end)
                    return true;
            end;
        end;

        if timed_out(wait_end)
        begin
            RIncomplete("await_presence: Descriptor did not appear, time limit = {time_limit}",v_level);
            RStatus("∂t∂t{feature_desc}", v_level);
            RDumpState(,v_level);
            return false;
        end;

        # Wait a bit, to reduce traffic when VU is running on the campus net.
        wait(0,0,0,250);
    end;
end;

#########################################################################
#    task        await_absence(feature_desc, time_limit, persistence, exact, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Wait for the feature with descriptor {feature_desc} to
#                    disappear. If more than {time_limit} seconds pass, then
#                    return a false (error) result. If the feature is gone,
#                    return a true result. If a non-zero {persistence} is
#                    specified, wait for the feature to be absent for
#                    {persistence} seconds.  Use this library call instead
#                    of just wait() whenever possible because it's more robust.
#    Parameters:        feature_desc:    descriptor of thing to look for
#                    time_limit:        how long to wait in seconds
#                    persistence:    how long to ensure that the object
#                                    stays around.
#                    exact:            whether to perform an EXACT match
#                    v_level:        verbosity level for log output
#                                    Pass a v_level of 6 to silence errors
#                                    and not have them add up for the test summary
#    Returns:        success:    true
#                    failure:    false
#    Examples:        if (await_absence ([window t:'Find' o:1], 300) = error)
#                            #Wait up to 300 seconds for the dialog to disappear.
#                    return(incomplete);
#                            #If it does not appear, then return 'incomplete'.
#                    else    #otherwise  call the task  "Drag_Trash".
#                       DragTrash('My Folder', true);
#    Assumptions:    We assume that {persistence} will be less than 3600
#                    (one hour) and that the {time_limit} will be less than
#                    86400 (a day).
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90 Alan Liu        Creation as part of ApplicationLib.vu for 007
#        3/4/92  Jason Marsh        Incorporation into Clouseau.Lib.
#        06/12/93    SBR            Modified to use Errors.lib
#        12/15/93    JDL            Corrected return information in the description
#                                area of the header
#        05/25/94    SBR            Modified to use _MatchBoolean instead of _Match
#        06/07/94    SBR            Modified to use timed_out() instead of timer()
#        09/27/96    BRL/MSO        Added SPEC exception handling
#        04/07/97    SBR            Added wait() to reduce network traffic for CHAT.
#########################################################################
task    await_absence(feature_desc, time_limit := 10, persistence := 0,
            exact := true, v_level := 5)
begin
    wait_end := get_end_time(time_limit);    # Reset the time limit timer
    persist_end := 0;                        # Reset the persistence timer

    while true
    begin
        found := _MatchBoolean(feature_desc, exact);
        if found
            persist_end := 0;                # Still there; reset persistence
        else
        begin
            if not persistence
                return true;
            else
            begin
                if not persist_end
                    persist_end := get_end_time(persistence);
                if timed_out(persist_end)
                    return true;
            end;
        end;

        if timed_out(wait_end)
        begin
            RIncomplete("await_absence: Descriptor did not disappear, time limit = {time_limit}",v_level);
            RStatus("∂t∂t{feature_desc}", v_level);
            RDumpState(,v_level);
            return false;
        end;

        # Wait a bit, to reduce traffic when VU is running on the campus net.
        wait(0,0,0,250);
    end;
end;


#########################################################################
#    task        balloon_await_presence(time_limit, persistence, exact, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Wait for the balloon to appear. If more than {time_limit} seconds
#                    pass, then return a false (error) result. If the feature is found,
#                    return a true result. If a non-zero {persistence} is
#                    specified, wait for the feature to be present for
#                    {persistence} seconds.  Use this library call instead
#                    of just wait() whenever possible because it's more robust.
#    Parameters:        time_limit:        how long to wait in seconds
#                    persistence:    how long to ensure that the object
#                                    stays around.
#                    exact:            whether to perform an EXACT match
#                    v_level:        verbosity level for log output
#                                    Pass a v_level of 6 to silence errors
#                                    and not have them add up for the test summary
#                    expected:        list of correct checksums.
#    Returns:        success:    true
#                    failure:    false
#    Examples:        await_presence(20)
#                            #Wait up to 20 seconds for a balloon to appear.
#    Assumptions:    We assume that {persistence} will be less than 3600
#                    (one hour) and that the {time_limit} will be less than
#                    86400 (a day).
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        07/25/90 Alan Liu                Creation as part of ApplicationLib.vu for 007
#        05/10/95 Geraldine O'Sullivan    Modified to wait for correct balloon to appear.
#########################################################################
task    balloon_await_presence(time_limit := 10, persistence := 0, v_level := 5, expected)
begin
    wait_end := get_end_time(time_limit);    # Reset the time limit timer
    persist_end := 0;                        # Reset the persistence timer

    while true
    begin
        actual:= VUAid("Balloon");
        if typeOf(expected) = 'list'
            success := isMember(actual, expected);
        else
            success := (actual = expected);

        if not success
            persist_end := 0;                # No match; reset persistence
        else
        begin
            if not persistence
                return true;
            else
            begin
                if not persist_end
                    persist_end := get_end_time(persistence);
                if timed_out(persist_end)
                    return true;
            end;

            if timed_out(wait_end)
                return false;
        end;
    end;
end;


#########################################################################
#    task                    type_keys(key_list, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Performs the same function that type k:key_list would,
#                    with the addition of a few new symbols:
#                        'down'         causes the following key to be pressed
#                        'up'        causes the following key to be released
#                        'latch'        causes the following key to be pressed
#                                    only for a single keystroke.
#                        'waitx'     wait 'x' seconds (9 maximum)
#    Parameters:        key_list:        list of keyboard actions to perform, may
#                                    contain any 'type' command input, and the
#                                    keywords listed above.
#                    v_level:        verbosity level for log output
#    Returns:        true
#    Examples:        type_keys({'down', shiftKey, 'a', 'bc', 'latch', optionKey,
#                                'qu', 'x', 'up', shiftKey, 'p', 'down', shiftKey, 'x'});
#                        # Causes the string 'ABCάpX' to be typed.
#    Assumptions:    Multiple latched keys may be specified by latching one
#                    after the other: {'latch', shiftKey, 'latch', commandKey, 'A'}
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90 Alan Liu        Creation as part of ApplicationLib.vu for 007
#        3/4/92  Jason Marsh        Incorporation into Clouseau.Lib.
#        12/15/93    JDL            Added documentation of wait function to header
#        09/27/96  BRL/MSO        Added SPEC exception handling
#########################################################################
task    type_keys(key_list := {}, v_level:= 5)
begin
    latchList := {};        (*These keys have been latched*)
    mode := 'idle';         (*Mode can be 'idle', 'down', 'up', or 'latch'*)
    if RXStatus (v_level) println "type_keys: typing ", key_list;

    for i := 1 to card key_list
    begin
        key := key_list[i];

        if key ~= /wait≈/
            wait(strToNum(key[5]));
        else
        begin
            if (mode = 'idle')
            begin
                if (key = 'down' or key = 'up' or key = 'latch')
                    mode := key;
                else
                begin
                    _Type({key});
                    if latchList
                    begin
                        _ReleaseKey(latchList);
                        latchList := {};
                    end;
                end;
            end;
            else if (mode = 'latch' or mode = 'down')
            begin
                _PressKey({key});
                if (mode = 'latch')
                    latchList := insert(key, 1 + card latchList, latchList);
                mode := 'idle';
            end;
            else if (mode = 'up')
            begin
                _ReleaseKey({key});
                mode := 'idle';
            end;
        end;
    end;

    if latchList
        _ReleaseKey(latchList);
    return true;                #always returns true
end;


#########################################################################
#    task                    select_descriptor(itemDesc, timeLimit, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Select an item by its descriptor.  Possible descriptors
#                    currently are: windows, check boxes, buttons, radio
#                    buttons, menus, and menu items.  If the descriptor is
#                    a checkbox it checks to see if its setting changed.
#                    If it is a radio button it check to see if it is on
#                    after it was selected.
#    Parameters:        itemDesc:        a descriptor of the item you want to select
#                    timeLimit:        if <> 0 call await_presence with this time_limit
#                    v_level:        verbosity level for log output
#    Returns:        success: true, failure: false
#    Examples:        select_descriptor([button t:'OK']);
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        2/27/91        EH        Creation as part of SelectLib.vu for 007.
#        3/4/92        Jason Marsh        Incorporated into Clouseau.Lib.
#        05/27/93    SBR        Added v_level to 'Unable to find' errors
#        06/12/93      SBR        Modified to use Errors.lib
#########################################################################
task    select_descriptor(itemDesc := '', timeLimit := 0, v_level := 5)
begin
    error := false;
    noErr := true;

    ## See if we got anything
    if not (itemDesc)
        return error;

    ## Wait for item to appear
    if timeLimit <> 0
    begin
        if not (await_presence(itemDesc,timeLimit))
        begin
            if RXIncomplete(v_level)
                println "select_descriptor: Unable to find '",itemDesc,"'";
            RDumpState(descType(itemDesc),v_level);    #Dump diagnostic info
            return error;
        end;
    end;
    else
    begin
        found := _Match(itemDesc,true);                #exact match
        if not found
        begin
            if RXIncomplete(v_level)
                println "select_descriptor: Unable to find '",itemDesc,"'";
            RDumpState(descType(itemDesc),v_level);    #Dump diagnostic info
            return error;
        end;
    end;

    beforeDesc := found;                        #save descriptor's state before selecting
    descriptorType := descType(itemDesc);

    ## Select item
    if descriptorType = 'window'                 #check for the Desktop "window"
        if beforeDesc.r = {0,0,0,0}             #RIncomplete always returns false
            return RIncomplete("select_descriptor: no windows are open to select",v_level);


    selected := _SelectBoolean(itemDesc, true);
    if not selected
        return RIncomplete("select_descriptor: Error while selecting {itemDesc}",v_level);

    if (descriptorType = 'radiobutton' or descriptorType = 'checkbox')
    begin
        afterDesc := _Match(itemDesc, true);
        if not afterDesc
            return RIncomplete("select_descriptor: Error verifying {descriptorType}, it was not found",v_level);

        ## Now check to see if what we did worked only for checkboxes and
        ## radiobuttons.  Do not check when selecting menus, menu items,
        ## buttons, and windows.
        if (descriptorType = 'checkbox')
        begin
            if (beforeDesc.s = afterDesc.s)
                if RXIncomplete(1)
                    println "select_descriptor: Check box titled '",afterDesc.t,"' did not change it's setting";
        end;
        else if (descriptorType = 'radiobutton')
        begin
            if not (afterDesc.s = { 1,1 })
                if RXIncomplete(1)
                    println "select_descriptor: Radio button titled '",afterDesc.t,"' did not become set";
        end;
    end;
    if RXStatus(v_level)
        println "select_descriptor: ", itemDesc , " selected";
    return noErr;
end;

(*
#########################################################################
#    task                    select_descriptor_CP(itemDesc, timeLimit, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Select an item by its descriptor.  Possible descriptors
#                    currently are: windows, check boxes, buttons, radio
#                    buttons, menus, and menu items.  If the descriptor is
#                    a checkbox it checks to see if its setting changed.
#                    If it is a radio button it check to see if it is on
#                    after it was selected.
#            NOTE:    This task is identical to select_descriptor() in Clouseau.lib,
#                    except it checks if the front window's title is in the list of
#                    control panels with the dreaded "-89 offset". If the window is
#                    one of the bad ones, and the descriptor is a contentItem, the
#                    task adds 89 horizontally and does a manual click on the item,
#                    otherwise it acts normally. This task will become obsolete when
#                    we switch to VU 2.1, which corrects the -89 offset by itself.
#            NOTE:    This task does not fix the problem in VU 2.0.1 of items which
#                    end up outside the content region after being "moved" by -89.
#                    In these cases VU does not allow access to these descriptors
#                    by match or select, so VUAid has to verify the setting.
#    Parameters:        itemDesc:        a descriptor of the item you want to select
#                    timeLimit:        if <> 0 call await_presence with this time_limit
#                    v_level:        verbosity level for log output
#    Returns:        success: true, failure: false
#    Examples:        select_descriptor([button t:'OK']);
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        2/27/91        EH        Creation as part of SelectLib.vu for 007.
#        3/4/92        Jason Marsh        Incorporated into Clouseau.Lib.
#        05/27/93    SBR        Added v_level to 'Unable to find' errors
#        06/12/93      SBR        Modified to use Errors.lib
#        06/14/94      SBR        Added -89 offset correction
#        09/27/96      BRL/MSO    Added SPEC exception handling
#########################################################################
#task    select_descriptor_CP(itemDesc := '', timeLimit := 0, v_level := 5)
begin
    error := false;
    noErr := true;

    ## See if we got anything
    if not (itemDesc)
        return error;

    ## Wait for item to appear
    if timeLimit <> 0
    begin
        if not (await_presence(itemDesc,timeLimit))
        begin
            if RXIncomplete(v_level)
                println "select_descriptor: Unable to find '",itemDesc,"'";
            RDumpState(descType(itemDesc),v_level);    #Dump diagnostic info
            return error;
        end;
    end;
    else
    begin
        found := _Match(*Boolean*)(itemDesc,true);                #exact match
        if not found
        begin
            if RXIncomplete(v_level)
                println "select_descriptor: Unable to find '",itemDesc,"'";
            RDumpState(descType(itemDesc),v_level);    #Dump diagnostic info
            return error;
        end;
    end;

    beforeDesc := found;                        #save descriptor's state before selecting
    descriptorType := descType(itemDesc);

    ## Select item
    if descriptorType = 'window'                 #check for the Desktop "window"
        if beforeDesc.r = {0,0,0,0}             #RIncomplete always returns false
            return RIncomplete("select_descriptor: no windows are open to select",v_level);


    selected := _SelectBoolean(itemDesc, true);
    if not selected
        return RIncomplete("select_descriptor: Error while selecting {itemDesc}",v_level);

    if (descriptorType = 'radiobutton' or descriptorType = 'checkbox')
    begin
        afterDesc := _Match(*Boolean*)(itemDesc, true);
        if not afterDesc
            return RIncomplete("select_descriptor: Error verifying {descriptorType}, it was not found",v_level);

        ## Now check to see if what we did worked only for checkboxes and
        ## radiobuttons.  Do not check when selecting menus, menu items,
        ## buttons, and windows.
        if (descriptorType = 'checkbox')
        begin
            if (beforeDesc.s = afterDesc.s)
                if RXIncomplete(1)
                    println "select_descriptor: Check box titled '",afterDesc.t,"' did not change it's setting";
        end;
        else if (descriptorType = 'radiobutton')
        begin
            if not (afterDesc.s = { 1,1 })
                if RXIncomplete(1)
                    println "select_descriptor: Radio button titled '",afterDesc.t,"' did not become set";
        end;
    end;
    if RXStatus(v_level)
        println "select_descriptor: ", itemDesc , " selected";
    return noErr;
end;
*)

#########################################################################
#    task            select_menuItem(menuName1, menuName2, menuName3, keyEquiv, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Selects a menu item by its name. Each menuName parameter can be a
#                    string or regular expression representing the title, or an integer
#                    denoting the ordinal. The menuItem descriptor built from these
#                    parameters is matched exactly (with !) and checked for enablement,
#                    then it is selected exactly. Exact match and select are much faster
#                    than inexact. If you want to specify a partial menuName, use the
#                    wildcard (?≈) characters in a regular expression. (see example)
#    Parameters:        menuName1:        Menu item to be selected.
#                    menuName2:        Menu name if non-hier menu and
#                                     Level 2 menu item if hier menu.
#                    menuName3:        Menu name if hier menu.
#                    keyEquiv:        true: use command key equivalent if available
#                                    false: always select the menu item
#                    v_level:        verbosity level for log output
#    Returns:        true for successful selection, false for unsuccessful.
#    Examples:        select_menuitem("Save", "File");
#                    select_menuitem("Scrapbook", 1);
#                    select_menuitem(/≈h≈w b≈ll≈/);    (this selects Show Ballons)
#    Assumptions:    Do not have to pass 'menuName2' or 'menuName3'
#                    as a parameter.  In that case, default value, "",
#                    will be used.
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        4/4/90        SL        Created
#        3/27/92     JM        modified from Controls.lib and included in Clouseau
#        04/02/93     SBR        Added select by ordinality
#        04/02/93     SBR        Fixed selecting sub-menuItems using only menuID1
#        04/02/93     SBR        More descriptive output when verbose
#        06/12/93      SBR        Modified to use Errors.lib except for VU bug fix
#        09/27/96      BRL/MSO    Added SPEC exception handling
#########################################################################
task select_menuItem(menuID1, menuID2 := "", menuID3 := "", keyEquiv := false, v_level := 4)
begin
    if (typeOf(keyEquiv) = 'integer') and (v_level = 5)
    begin
        if isUndefined(global __gBadSMI__)
        begin
            RStatus('The select_menuItem parameter list has changed. Your script should still work.',1);
            RStatus('This message will occur only once per run.',1);
            __gBadSMI__ := true;            #only print the message once;
            v_level := 1;                    #be verbose to help locate this call
        end;
        else
            v_level := keyEquiv;            #assume the integer was a valid v_level

        keyEquiv := false;
    end;

    if typeOf(menuID1) <> 'integer'
    begin
        if menuID2
        begin
            if menuID3
                if typeOf(menuID2) <> 'integer'
                    ourMenuItem := _Match([menuItem t:menuID1 m:[menuItem t:menuID2 m:menuID3]], true);
                else
                    ourMenuItem := _Match([menuItem t:menuID1 m:[menuItem o:menuID2 m:menuID3]], true);
            else
                ourMenuItem := _Match([menuItem t:menuID1 m:menuID2], true);
        end;
        else
            ourMenuItem := _Match([menuItem t:menuID1], true);
    end;
      else begin
        if menuID2
        begin
            if menuID3
                if typeOf(menuID2) <> 'integer'
                    ourMenuItem := _Match([menuItem o:menuID1 m:[menuItem t:menuID2 m:menuID3]], true);
                else
                    ourMenuItem := _Match([menuItem o:menuID1 m:[menuItem o:menuID2 m:menuID3]], true);
            else
                ourMenuItem := _Match([menuItem o:menuID1 m:menuID2], true);
        end;
        else
            ourMenuItem := _Match([menuItem o:menuID1], true);
    end;

    keyString := '';
    mString := '';
    theError := '';
    if not ourMenuItem theError := 'the match failed';
    else omi := ourMenuItem;        # a shorter name
    if (omi)                          # menu item exists and there was no error
    begin
        isHierarchical := descType(omi.m) = 'menuItem';
        if isHierarchical
        begin
            ########################################################
            ##### This 2nd match is necessary because of a VU bug - VU "loses" the top menu when you
            ##### put a hierarchical menu into a variable. Then, selecting and matching take much
            ##### more time for hierarchical menus (e.g. 5-9 seconds per). Bug exists in
            ##### VU 2.0.1 and previous versions. The only other alternative is to select without
            ##### matching first, but this bypasses all the nice error detection.
            ##### To save time after bug is fixed, simply remove or comment out this section
            _menuBugExists__ := true;
            if not menuID3
            begin
                try
                    match [menuItem t:omi.t o:omi.o m:[menuItem t:omi.m.t o:omi.m.o m:[menu t:?t1 o:?t2]]]!;
                catch theError
                    ExceptionDispatcher(theError,,{"match 1  in select_menuItem", {menuID1, menuID2, menuID3, keyEquiv, v_level}});
            end;
            else if typeOf(menuID3) = 'string'
            begin
                t1 := menuID3;
                try
                    match [menuItem t:omi.t o:omi.o m:[menuItem t:omi.m.t o:omi.m.o m:[menu t:t1 o:?t2]]]!;
                catch theError
                    ExceptionDispatcher(theError,,{"match 2  in select_menuItem", {menuID1, menuID2, menuID3, keyEquiv, v_level}});
            end;
            else
            begin
                t2 := menuID3;
                try
                    match [menuItem t:omi.t o:omi.o m:[menuItem t:omi.m.t o:omi.m.o m:[menu t:?t1 o:t2]]]!;
                catch theError
                    ExceptionDispatcher(theError,,{"match 3  in select_menuItem", {menuID1, menuID2, menuID3, keyEquiv, v_level}});
            end;
            if temp[1]
                theError := temp[2];

            if _menuBugExists__
                hierMenu := [menu t:t1 o:t2];    # execute this statement before bug is fixed
            else
            ########################################################
            hierMenu := omi.m.m;                # execute this statement after bug is fixed
        end;

        if theError;
        else if not (omi.e)
            theError := "it is disabled";
        else
        begin
            if keyEquiv
            begin
                theChar := omi.k;
                if theChar                         # command key equivalent?
                begin
                    if theChar ~= /[A-Z]/             # do not press shift key for normal cmd-key
                        theChar := codeToCharacter(32 + characterToCode(theChar));
                    key_eq(theChar);
                    keyString := ", by its key equivalent";
                end;
                else
                begin
                    keyString := ", no VU-visible key equivalent";
                    keyEquiv := false;
                end;
            end;
            if not keyEquiv                     # if not select normally
            begin
                if isHierarchical
                    temp := _SelectBoolean(
                                [menuItem t:omi.t o:omi.o m:[menuItem t:omi.m.t o:omi.m.o m:hierMenu.t]],true);
                else
                    temp := _SelectBoolean([menuItem t:omi.t o:omi.o m:[menu t:omi.m.t o:omi.m.o]],true);
                if not temp
                    theError := 'VU could not select it';
            end;
        end;
    end;

    if R_BeVerbose(v_level)                     # skip fancy reporting normally
    begin
        if not omi                                 # menu item does not exist
        begin
            if menuID3
                mString := "{menuID1} from menu item {menuID2} from menu {menuID3}";
            else if menuID2
                mString := "{menuID1} from menu {menuID2}";
            else
                mString := "{menuID1}";
            theError := "it does not exist";
        end;
        else
        begin
            menu1Ord := omi.o;
            menu2Ord := omi.m.o;
            if isHierarchical
            begin
                menu3Ord := hierMenu.o;
                mString := "'"+omi.t+"'" + " ({menu1Ord})" + " from menu item " + "'"+omi.m.t+"'" +
                    " ({menu2Ord})" + " from the " + "'"+hierMenu.t+"'" + " menu" + " ({menu3Ord})";
            end;
            else
                mString := "'"+omi.t+"'" + " ({menu1Ord})" + " from the " + "'"+omi.m.t+"'" + " menu"
                    + " ({menu2Ord})";
        end;
        if theError
            RIncomplete("select_menuItem: Failed to select {mString}{keyString} because {theError}",v_level);
        else
            RStatus("select_menuItem: Selected {mString}{keyString}" ,v_level);
    end;
    if theError
        return false;
    else
        return true;
end; # select_MenuItem()



#########################################################################
#    task            move_mouse(action_list, waitState, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    This task is a mouse equivalent to type_keys.  Pass it
#                    an action_list (see example below) to execute, waiting
#                    between each action for a waitState second.  Warning:
#                    this routine  automatically releases the mouse for you
#                    if you leave it down, and it does release the ShiftKey
#                    if you leave it down.  This routine runs very fast, and
#                    may require a waitState and/or 'waitx' statements to
#                    produce solid results.
#    Parameters:        actionList:        List of possible actions:
#                        {X,Y} - move to location
#                        {l,t,r,b} - move to center of rectangle
#                        'relative' - relative to last click mode
#                        'relToWindow' or 'rtw' - relative to window rect mode
#                        'relToBounds' or 'rtb' - relative to window bounds mode
#                        'absolute' - absolute mode
#                        'click' - do a mouse click
#                        'doubleClick' - do a doubleClick
#                        'down' - do a pressMouse
#                        'up'- do a releaseMouse
#                        'press' - press down the following key
#                        'release' - release the following key
#                        'waitx' - wait 'x' seconds (9 maximum)
#                    waitState:        How long to pause between individual
#                                    actions.
#                    v_level:        verbosity level for log output
#    Returns:        true if you sent it a valid list, false if not
#    Examples:                #this example will select the first and fourth items
#                            #in a non-icon window and drag them both to the trash.
#                    scr := match[screen];        #find the trash -- hopefully!#
#                    trshX := scr.r[3] - 48; trshY := scr.r[4] - 43;
#                    move_mouse({ { 25,50 },'click','press', ShiftKey, { 25,100 },
#                        'click','release', ShiftKey, 'absolute', 'down', {trshX,trshY}});
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/04/92    Jason Marsh        Created
#        07/12/94    SBR                Fixed bug where we can leave keys pressed. It had
#                                    released some modifiers but not all pressed keys.
#        09/27/96      BRL/MSO            Added SPEC exception handling
#        03/20/97      SBR                Added {l,t,r,b} (move to center of rect) action
#        04/14/97      SBR                Added 'relToBounds' action
#########################################################################
task    move_mouse(action_list := {}, waitState := 0, v_level:= 5)
begin
    mode := 'relToWindow';         #Mode can be 'relative', 'relToWindow',
                                    # 'relToBounds' or 'absolute'
    if RXStatus (v_level)
        println "move_mouse: doing ", action_list;

    # 07/12/94 SBR: new code with keysPressed is to ensure all pressed keys are released
    keysPressed := {};

    for i := 1 to card action_list
    begin
        action := action_list[i];

        if typeOf(action) = 'list'                 # If it's coordinates, move there
        begin
            if card action = 4
            begin
                # Calculate the center point of a 4-item rectangle.
                action := {(action[1] + action[3])/2, (action[2] + action[4])/2};
            end;

            if (mode = 'relToWindow' or mode = 'rtw')
            begin
                if IsUndefined(windowRect)
                begin
                    try
                        match [window o:1 r:?windowRect]!;
                    catch theError
                        ExceptionDispatcher(theError,,{"match 1 in move_mouse()",
                                                {action_list, waitState, v_level}});
                end;
                _Move('a',{ windowRect[1] + action[1], windowRect[2] + action[2] });
            end;
            else if (mode = 'relToBounds' or mode = 'rtb')
            begin
                if IsUndefined(windowBounds)
                begin
                    try
                        match [window o:1 b:?windowBounds]!;
                    catch theError
                        ExceptionDispatcher(theError,,{"match 2 in move_mouse()",
                                                {action_list, waitState, v_level}});
                end;
                _Move('a',{ windowBounds[1] + action[1], windowBounds[2] + action[2] });
            end;
            else if (mode = 'absolute')
                _Move('a',{ action[1], action[2]});
            else
                _Move('r',{ action[1], action[2]});
        end;
        else if action = 'click'
            _Click();
        else if action = 'doubleClick'
            _DoubleClick();
        else if isMember(action, { 'relative','absolute','rtw','relToWindow',
                                        'rtb','relToBounds'})
            mode := action;
        else if action = 'down'
            _PressMouse();
        else if action = 'up'
            _ReleaseMouse();
        else if action = 'press'
        begin
            i:= i+1;
            theKey := action_list[i];
            _PressKey({theKey});
            keysPressed := keysPressed + {theKey};
        end;
        else if action = 'release'
        begin
            i:= i+1;
            theKey := action_list[i];

            _ReleaseKey({theKey});
            releasedIndex := isMember(theKey, keysPressed);
            if releasedIndex
                keysPressed := remove(releasedIndex, keysPressed);
        end;
        else if action ~= /wait≈/
            wait(strToNum(action[5]));
        else
        begin
            _ReleaseMouse();            # release possible pressed items before returning
            for each theKey in keysPressed
                _ReleaseKey({theKey});
            return RIncomplete("move_mouse: incorrect command: {action_list}");
        end;
        if waitState > 0
            wait(waitState);
    end;     #for i := 1 to card action_list

    _ReleaseMouse();                    # release possible pressed items
    for each theKey in keysPressed
        _ReleaseKey({theKey});

#        _ReleaseKey({shiftKey});        # 07/12/94 SBR commented out (new clean up method)
#        _ReleaseKey({optionKey});
#        _ReleaseKey({commandKey});
    return true;
end;


#########################################################################
#    task                    select_popup(cntrlDesc, value)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    This task is a general purpose popup menu selector. It
#                    is for popup menus which VU can only see as a control.
#                    To combat the problem of menus which don't fit on the
#                    screen and become scrollable when they are selected,
#                    this task moves up or down the menu one item at a time.
#    Parameters:        cntrlDesc:        A descriptor of the control.
#                    value:            The desired item number where the lowest is 0.
#    Returns:        success: true, failure: false
#    Examples:        select_popup("Geneva", 4);
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        2/27/91        EH        Creation as part of SelectLib.vu for 007.
#        3/4/92        Jason Marsh        Incorporated into Clouseau.Lib.
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    select_popup(cntrlDesc, value)
begin
    # variables for return values
    complete := true;         # result code RETURNED if tool could be completely run
    incomplete := false;     # result code RETURNED if tool could not be completely run
    status := complete;        # result code to be returned by this task

    if not (cntrlDesc)
        return RIncomplete("select_popup: Empty descriptor");            # RIncomplete always returns false

    if not (await_presence(cntrlDesc))                                    # Make sure popup is visible.
        return RIncomplete("select_popup: Could not find control");


    cntrlDesc := _Match(cntrlDesc);
    cntrlLoc := cntrlDesc.r;                                    # Location of control.
    cntrlSet := cntrlDesc.s;                                    # What the control is set to.

    if (cntrlSet[1] = value)                                            # don't do anything if we already have the right value.
         return complete;

    if ((value > cntrlSet[2]) or (value < 0))                             # value not in possible range.  0 is assumed to be the
        return incomplete;                                                # lowest value since we have no way of knowing.

    if (cntrlSet[1] > value)
    begin
          dist := -16;                                                    # move up the popup 'stop' times
        stop := cntrlSet[1] - value;
    end;
    else
    begin
          dist := 16;                                                        # move down the popup 'stop' times
        stop := value - cntrlSet[1];
    end;

    for i := 1 to stop
    begin
        _Move('a',{(cntrlLoc[3] - 10), (cntrlLoc[4] - 10)});            # Move mouse to control.
        _PressMouse();                                                    # press button
        wait(1);                                                        # wait a second for control to select.
        _Move('r',{0, dist});                                        # move up or down to select item in popup
        wait(1);                                                        # wait for control to catch up to mouse.
        _ReleaseMouse();                                                # release button to select.
          wait(1);
    end;

    return complete;
end;


#########################################################################
#    task                    twitch(appName, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Click on the twitch icon.  If appName (regular expr)
#                    is supplied, keep twitching until we reach the desired
#                    application, or until we cycle through everything.
#    Parameters:        appName:        name of process to switch to.
#                    v_level:        verbosity level for log output
#    Returns:        false if we are still in the same application after
#                    attempting to twitch. This will also happen if a
#                    non-existent appName is passed in.
#    Examples:        twitch("Scrapbook");
#    Assumptions:    We assume that the first FOUR items of the application
#                    are NOT application names, and that the rest are.
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90        Alan Liu        Creation as part of FinderLib.vu for 007
#        3/4/92        Jason Marsh        Incorporated into Clouseau.Lib
#        10/27/93    SBR                Added v_level to twitch failure
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    twitch(appName := "",v_level := 5)
begin
    global g_CurApName;

    try
        match [application t:?g_CurApName]; (*name of the current app*)
    catch theError
        ExceptionDispatcher(theError,,{"match 1 in twitch", {appName,v_level}});

    if g_CurApName = appName
        return RStatus("twitch: current application is {appName}",v_level);
    start_app := g_CurApName;

    try
        match [menuItem t:'Hide Others' m:[menu o:?appMenu]]!; (*will return 0 if can't find it*)
    catch theError
        ExceptionDispatcher(theError,,{"match 2 in twitch", {appName,v_level}});

    if appMenu
    begin
        if appName
        begin
            _Select([menuItem t:appName m:appMenu], true);
        end;
        else
        begin
            try
                tMatch := match [menuItem m:appMenu c:'' o:?i]!;
            catch theError
                ExceptionDispatcher(theError,,{"match 3 in twitch", {appName,v_level}});

            if tMatch
            begin
                j := i+1;
                if not _MatchBoolean([menuItem m:appMenu o:j])
                    j := 5;
                if i <> j
                    _Select([menuItem m:appMenu o:j], true);
            end;
        end;
    end;

    wait(1); (*if we don't do this we match the original app again*)

    try
        match [application t:?g_CurApName]!;
    catch theError
        ExceptionDispatcher(theError,,{"match 4 in twitch", {appName,v_level}});

    if g_CurApName = start_app
    begin
        if g_CurApName <> "Finder"
            return RIncomplete ("twitch: {appName} unsuccessful.  Current application is '{g_CurApName}'",v_level);
        else
            return RStatus ("twitch: only Finder currently running",v_level);
    end;
    else
        return RStatus ("twitch: {appName} successful.  Current application is '{g_CurApName}'",v_level);
end;


#########################################################################
#    task                    close_all_windows(keepWindow, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Close all windows except the named window, in an effort
#                    to bring it to the front.  Return false if successful
#                    (the named window is now frontmost), true on failure.
#                    If keepWindow is empty ("") then all windows will be closed.
#                    We watch for the System 7.X 'Desktop' window and try
#                    to send it to the back when we encounter it. If it is
#                    the only window open, then we return.
#    Parameters:        keepWindow:        name of window to keep open
#                    v_level:        verbosity level for log output
#    Returns:        Nothing
#    Examples:        close_all_windows();
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90        Alan Liu        Creation as part of WindowLib.vu for 007
#        03/04/92    Jason Marsh        Incorporated into Clouseau.Lib
#        09/04/95    SBR                Radar 1272777: Changed from true to false (below)
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    close_all_windows(keepWindow := "", v_level:=5)
begin
    stop := false;

    try
        frontWind := match [window o:1 t:?frontName];
    catch theError
        ExceptionDispatcher(theError,,{"match 1 in close_all_windows", {keepWindow, v_level}});

    while frontWind and (not stop)
    begin
        if _MatchBoolean([window o:1 r:{0,0,0,0}])            # Desktop is in front
        begin
            if _MatchBoolean([window o:2])
                _Select([window o:2], true);
            else
                stop := true;
        end;
        else
        begin
            if (keepWindow and (frontName = keepWindow))
                return true;
            else if dismiss_dialog(,v_level)
            begin
                # Changed from "stop := true" for Radar 1272777
                stop := false;
            end;
        end;

        try
            frontWind := match [window o:1 t:?frontName];
        catch theError
            ExceptionDispatcher(theError,,{"match 2 in close_all_windows", {keepWindow, v_level}});
    end;
    return not (keepWindow <> "");
end;


#########################################################################
#    task                    relocate_window(newRect, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Set the front window to the given rect.
#                    Checks to make sure the size box is not moved offscreen
#                    before it is used. Also handles situations that would
#                    require more than a two-step drag-size call.
#    Parameters:        newRect:        new location and size of window
#                    v_level:        verbosity level for log output
#    Returns:        true if the move was successful
#                    false if the move failed.
#    Examples:        relocate_window({100,100,230,230});
#    Assumptions:    Assumes only 1 monitor is connected, or that the window
#                    is/will be completely on the menu monitor.
#                    Also re-sizes windows in two steps - horizontally and
#                    vertically, rather than one smooth diagonal movement.
#                    Does not account for illegal moves of windows caused by
#                    dragging them onto the menubar, though this does will
#                    result in a FAIL result.
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90     Alan Liu        Creation as part of WindowLib.vu for 007.
#        8//91        Jonathan Marsh    Robusticised it.
#        3/23/92        Jason Marsh        Incorporated into Clouseau.lib.
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    relocate_window(newRect := {2, 22, 202, 222}, v_level := 5)
begin
    rStatus("relocate_window:  Attempting to resize window to " + list_to_str(newRect), 4);

    try
        frontWind := match [window o:1 r:?oldRect]!;
    catch theError
        ExceptionDispatcher(theError,,{"match in relocate_window()", {newRect, v_level}});

    if (frontWind)
    begin
            # Note that this is defined only for the startup monitor.
            #    We check for legal windows against this screen only.
        screenRect := _Match([screen m:true], true).r;

            # If dragging before sizing results in the size box being dragged offscreen,
            #    then size before dragging.  In order to do this we ensure that the window
            #    is at its farthest left point (of old and new) before sizing it.
            # We must sometimes break this move into 3 steps (size,drag,size) - i.e. changing
            #    a short wide window near the bottom of the screen cannot be resized to
            #    a tall narrow window near the right of the screen in one drag, one size.
            # Therefore, break the horizontal and vertical moves down separately.

        if newRect[1] > oldRect[1]
        begin
            presizedW := TRUE;
            _Size([window o:1], 'w', {newRect[3]-newRect[1]} );
        end;
        if newRect[2] > oldRect[2]
        begin
            presizedH := TRUE;
            _Size([window o:1], 'h', {newRect[4]-newRect[2]} );
        end;

            # Do the drag if needed.
        if (oldRect[1] <> newRect[1] OR oldRect[2] <> newRect[2])
            _Drag(frontWind, 'a', {newRect[1], newRect[2]});

            # Do any sizing we haven't already done.
        if (oldRect[3] - oldRect[1]) <> (newRect[3] - newRect[1]) AND NOT presizedW
            _Size(frontWind, 'w', {newRect[3]-newRect[1]} );
        if (oldRect[4] - oldRect[2]) <> (newRect[4] - newRect[2]) AND NOT presizedH
            _Size(frontWind, 'h', {newRect[4]-newRect[2]} );

            # Make sure the window is actually in the right place.
        if _MatchBoolean([window o:1 r:newRect])
        begin
            if RXStatus(v_level)
                println "relocate_window: sized front window to ", newRect;
            return true;
        end;
        else
        begin
            rDumpState();
            return RIncomplete("relocate_window: resize window failed");
        end;
    end;
    else
        return RIncomplete("relocate_window: there is no front window");
end;


#########################################################################
#    task                    dismiss_dialog(preferredButton, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Dismiss a frontmost dialog, if there is one, resorting
#                    to whatever means are necessary (i.e., files may NOT
#                    be saved).  Algorithm:
#                        1. If there is a close box, call close_window().
#                        2. If there is a preferred button parameter, and
#                            it is present, use it.
#                        3. Examine the enabled buttons. If there is exactly
#                            one, select it, unless it contains the word 'launch'.
#                        4. If there are no enabled buttons, indicate an error.
#                        5. If there is more than one, apply our preference
#                            list -- if none of the preferred buttons is present,
#                            then do nothing and indicate an error.
#    Parameters:        preferredButton: Name of most likely button to dismiss dialog
#                    v_level:        verbosity level for log output
#    Returns:        true if successful, false if not
#    Examples:        dismiss_dialog();
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90     Alan Liu        Creation as part of WindowLib.vu for 007.
#        3/23/92        Jason Marsh        Incorporated into Clouseau.lib.
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    dismiss_dialog(preferredButton := "", v_level :=5)
begin
    try
        frontWind := match [window t:?tw o:1 c:?hasClose k:?kList r:?rw]!;
    catch theError
        ExceptionDispatcher(theError,,{"match in dismiss_dialog()", {preferredButton, v_level}});

    if frontWind
    begin
        if (hasClose)
            return close_window(tw,v_level);
        else if (preferredButton <> "" and _MatchBoolean([button t:preferredButton w:1 e:true]))
        begin
            _Select([button t:preferredButton w:1], true);
            return RStatus("dismiss_dialog selected preferred button ∂'{preferredButton}∂'",v_level);
        end;                                #RStatus always returns true
        else
        begin
            (*Remove everything except enabled buttons*)
            for i := card kList to 1 step -1
            begin
                if (not kList[i].e) or (descType(kList[i]) <> 'button')
                    kList := remove(i, kList);
            end;

            (*If there is just one enabled button, select it*)
            if (card kList = 1)
            begin
                if not (kList[1].t ~= /≈launch≈/)
                begin
                    _Select(kList[1], false);
                    if RXStatus(v_level)
                        println "dismiss_dialog: selected only enabled button ", kList[1];
                    return true;
                end;
            end;

            (*If there are no enabled buttons, signal a warning*)
            else if (card kList < 1)
                return RIncomplete("dismiss_dialog: No enabled buttons");    #RIncomplete always returns false

            (*Otherwise apply our preference list*)
            else
            begin
                buttonPref := {'Cancel', 'Quit', 'OK'};

                for i := 1 to card buttonPref
                begin
                    for j := 1 to card kList
                    begin
                        if kList[j].t = buttonPref[i]
                        begin
                            if select_descriptor(kList[j],v_level)
                                return true;
                        end;
                    end;
                end;

                (*Can't decide*)
                n := card kList;
                RIncomplete("dismiss_dialog: Multiple enabled buttons ({n})");
                return false;
            end;
        end;
    end;
    else return false;
end;


#########################################################################
#    task                    select_window(specifier, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Select the given window by using the built in VU select
#                    command.  Returns false if the window could not be
#                    found or otherwise failed to come to the front.
#    Parameters:        specifier:        name or ordinal of window to select
#                    v_level:        verbosity level for log output
#    Returns:        success: true, failure: false
#    Examples:        select_window("Control Panels");
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/25/90     Alan Liu        Creation as part of WindowLib.vu for 007.
#        3/23/92        Jason Marsh        Incorporated into Clouseau.lib.
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    select_window(specifier:="", v_level:= 5)
begin
     if(specifier = "")                         #RIncomplete always returns false
        return RIncomplete("select_window: Null specifier passed as a parameter");

    if not (TypeOf(specifier) = 'integer')
    begin
        theDesc := _Match([window t:specifier],true);
        if (not theDesc)
            return RIncomplete("select_window: Couldn't match a window of title: {specifier}");
    end;
    else if (specifier > 0)
    begin
        theDesc := _Match([window o:specifier],true);
        if (not theDesc)
            return RIncomplete("select_window: Couldn't match a window of ordinality: {specifier}");
    end;
    else if (specifier = 0)
    begin
        theDesc := _Match([window c:true g:true],true);
        if (not theDesc)
            return RIncomplete("select_window: No windows open");
    end;
    if theDesc.r = {0,0,0,0}                 #coordinates for the Desktop, which shows up as a window
        return RIncomplete("select_window: no windows are open to select");

    windOrd := theDesc.o;
    title := theDesc.t;
    if windOrd > 1
        _Select([window o:windOrd t:title], true);
    if not await_presence([window o:1 t:title])
        return RIncomplete("select_window: failed to select window");
    RStatus("select_window: selected window titled: '{title}' o: {windOrd}", v_level);
    return true;
end;


#########################################################################
#    task                    close_window(windName, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Close the named window, and wait for it to go away.
#                    This additional handshaking is sometimes helpful if
#                    scripts are running ahead of themselves. If no windName
#                    passed in, close the frontmost window.
#    Parameters:        windName:        name  of window to close
#                    v_level:        verbosity level for log output
#    Returns:        success: true, failure: false
#    Examples:        close_window("Control Panels");
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        07/25/90     Alan Liu        Creation as part of WindowLib.vu for 007.
#        03/23/92    Jason Marsh        Incorporated into Clouseau.lib.
#        02/22/95    SBR                added v_level to "has no close box" error msg
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    close_window(windName :="", v_level:= 5)
begin
    if windName = ""
    begin
        try
            match [window t:?windName o:1]!; #If no windName, close the frontmost window
        catch theError
            ExceptionDispatcher(theError,,{"match 1 in close_window()", {windName, v_level}});

        front := true;
    end;

    try
        windowToClose := match [window t:windName c:?hasClose r:?rw o:?WindOrd]!;
    catch theError
        ExceptionDispatcher(theError,,{"match 2 in close_window()", {windName, v_level}});

    if windowToClose
    begin
        if (hasClose)
        begin
            if windName = 'Alarm Clock'
            begin
                (*There's no real close box; fake it out*)
                _Move('a', {rw[1] + 16, rw[2] + 8});
                _Click();
            end;
            else if (rw = {0,0,0,0})
            begin
                if _MatchBoolean([window o:2])
                    _Select([window o:2], true);
                return false;
            end;
            else
            begin
                if windOrd > 1
                    if not (select_window(windName,v_level))
                        return false;
                RStatus("close_window: closing window ∂'{windName}∂'", v_level);

                _Close( [window o:1], true);
            end;
        end;
        else
            return RIncomplete("close_window: ∂'{windName}∂' has no close box", v_level);

        noErr := (await_absence( [window t:windName], 15 ));
        if not (noErr)
            RDumpState(,v_level);
        return noErr;
    end;
    else
        return RIncomplete("close_window: ∂'{windName}∂' not on screen");
end;


#########################################################################
#    task                    key_eq(key, modifier, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Type the key specified with the modifiers given.
#                    usage:  key_eq("o");
#    Parameters:        key:            Key to type
#                    modifier:        Modifier keys to hold down while pressing the key
#                        Command             = 1 (default)
#                        Option                 = 2
#                        Shift                = 3
#                        Control             = 4
#                        Command and Option    = 5
#                        Command and Shift    = 6
#                    v_level:        verbosity level for log output
#    Returns:        success: true, failure: false
#    Examples:        key_eq("o");      Use non-shifted characters for normal menu key commands
#                                    even though the menu manager displays them as shifted.
#                    key_eq("#");     Use shifted characters for FKEYs, e.g. cmd-shift-3,
#                                    or when a menu key command requires the shift key.
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        07/25/90    Alan Liu        Creation as part of WindowLib.vu for 007.
#        03/23/92    Jason Marsh        Incorporated into Clouseau.lib.
#        07/07/94    SBR                Added comments for shift key usage.
#        06/01/96    MSO                Added command and shift modifier
#        09/27/96      BRL/MSO            Added SPEC exception handling
#########################################################################
task    key_eq(key,modifier := 1, v_level:=5)
begin
    modifierList := { {commandKey},{optionKey},{shiftKey},{controlKey},{commandKey,optionKey},{commandKey,shiftKey} };
    RStatus("key_eq: typed the ∂'{key}∂' key with modifier {modifier}",v_level);
    _PressKey(modifierList[modifier]) ;
    wait(0,0,0,250);        # extra 1/4 second for the modifiers to register
    _Type({ key });
    _ReleaseKey(modifierList[modifier]);
    return true;
end;


#########################################################################
#    task    FindFile(pSearchArgument, pSearchBy, pSearchConstraint,
#                     pSearchLocation, pActionWhenFound, v_level)
#    Version 1.0d1
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Find a file in the System 7 Finder using the Find File DA.
#                    This version allows simple search criteria only. It is structured for
#                   time efficiency.
#    Parameters:        pSsearchArgument:    Value of the argument to search on.  This value
#                                        changes depending on the searchBy parameter as follows.
#                    pSearchBy:            What attribute of the file to search by.
#                    pSearchConstraint:    Searching constraints.  This value changes depending on the
#                                        pSearchBy parameter for the different searchBy values.
#
#                        pSearchBy        |    pSearchConstraint        |    pSsearchArgument (mandatory)
#                    --------------------+---------------------------+---------------------------------
#                        name (default)    | {contains (default),        |    <string>
#                                        |  starts with, ends with,    |
#                                        |  is, is not, doesn't         |
#                                        |  contain}                    |
#                        size            | †                            |    †
#                        kind            | {is, is not}                |    {alias, application, clipping
#                                        |                            |     file, ctrl panel, document,
#                                        |                            |     extension, folder, font,
#                                        |                            |     letter, sound, stationery}
#                        label            | †                            |    †
#                        date created    | †                            |    †
#                        date modified    | †                            |    †
#                        version            | {is, is not}                |    <string>
#                        comments        | †                            |    †
#                        lock attribute    | †                            |    †
#                        folder attribute| †                            |    †
#                        file type        | †                            |    †
#                        version            | †                            |    †
#                            †: not on this version
#                    pSearchLocation:    Where to perform search. Possible values are:
#                                        0         on all disks     (default)
#                                        1         on local disks
#                                        2        on mounted servers
#                                        3         on the desktop
#                                        4        in the finder selection
#                                        <str>    pSearchLocation
#                    pActionWhenFound:    Indicate the task what to do once the item has been found.
#                                        Possible values are:
#                                        launch:         quit Find File and open item (default).
#                                        open :         open item.
#                                        open folder: open the item's enclosing folder.
#                    v_level:    verbosity level for log output.
#                                v_level = 5    (default)
#    Returns:        true:    file found..
#                    false:    file not found
#    Examples:        findFile("QuickMail","name","contains",1,6);    # Search file 'QuickMail' on local disks.
#                    findFile("doom");                                # Search file 'Doom; on all disks.
#                    findFile('folder','kind','is not','backUp');    # Search all non-folders on 'backUp'.
#                    findFile('2.1',"version",'is',,open);            # Search files with V 2.1 on all disks
#                                                                        and open file w/o quiting Find File.
#    Assumptions:    VU 2.1.1.
#                    requires: Clouseau.lib, ExceptionHandling.lib, Report.lib, VUAid.tool.
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        09/09/96    Masa    Created.
#        09/16/96    Masa    included exception handling.
#        10/29/96    Masa    debugged version.
#        11/08/96    Masa    modified await_absence for 'Find File≈'
#        12/05/96    Masa    Changed logic: gItemNotFound to gItemFound
#        12/10/96    SBR/Masa    Added 50ms delay to [option] double-click for launch.
#                                modified await_absence for 'Find File≈' from window to application
#        01/31/97    SBR        Removed global gItemFound; return true/false, not badLaunch.
#########################################################################
task    FindFile(    pSearchArgument := '', pSearchBy := 'name', pSearchConstraint := 'is',
                    pSearchLocation := 0, pActionWhenFound := 'launch', v_level:= 3 )
begin
    # INITIALIZATION

    kSearchVolXCoord := 150;
    kSearchVolYCoord := 35;
    kSearchByXCoord := 80;
    kSearchByYCoord := 75;
    kPopUpDisplacement := 15;
    kConstraintRegionOffset := 3;
    kArgumentRegionOffset := 4;
    kMaxArgumentLength := 15;
    kXYOffset := 20;
    kAwaitTime := 60;

    found := false;


    # DISPLAY HEADER FOR FindFile() ON NOTEBOOK

    switch pSearchLocation
    begin
        case 0:        RStatus("   ∂'on all disks∂'",v_level);
        case 1:        RStatus("   ∂'on local disks∂'",v_level);
        case 2:        RStatus("   ∂'on mounted servers∂'",v_level);
        case 3:        RStatus("   ∂'on the desktop∂'",v_level);
        case 4:        RStatus("   ∂'in the finder selection∂'",v_level);
        default:    RStatus("   ∂'on {pSearchLocation}∂'",v_level);
    end;
    RStatus("initiating Find File for: ∂'{pSearchArgument} by {pSearchBy} {pSearchConstraint} on {pSearchLocation}∂'",v_level);



    # VALIDATE SEARCH ARGUMENT FIRST FOR EFFICIENCY.
    # If this parameter has no value then there is nothing we can do thus complain and quit!

    if (pSearchArgument = '')
    begin
        RError('FindFile: Search argument missing (i.e., 1st parameter)',v_level);
        return false;
    end;



    # GENERATE INTERNAL ORDINALITY FOR THE FIND FILE DIALOG BOX
    # This does not include all pSearchBy options yet.

    searchByOffset := assoc(pSearchBy, {{'name',0},{'kind',2},{'version',6}});
    switch pSearchBy
    begin
        case 'name':
            searchConstraintOffset := assoc(pSearchConstraint,
                                            {{'contains',0},{'starts with',1},{'ends with',2},{'is',3}});
        case 'kind':
        begin
            searchConstraintOffset := assoc(pSearchConstraint, {{'is',0},{'is not',1}});
            searchArgumentOffset := assoc(pSearchArgument, {{'alias',0},{'application',1},
                                         {'control panel',3},{'document',4},{'extension',5},{'folder',6}});
        end;
        case 'version':
            searchConstraintOffset := assoc(pSearchConstraint,
                                            {{'is',0},{'is not',1},{'ends with',2},{'is',3}});
        default:
        begin
            RError("FindFile: 'pSearchBy' parameter is invalid.",v_level);
            return false;
        end;
    end;



    # OPEN FIND FILE DA, MAKE THE FIND FILE WINDOW FRONTMOST, AND RELOCATE IT ON SCREEN IF NEEDED

    if not _MatchBoolean([application t:'Find File'])
    begin
        useAppleMenu := true;
        if _MatchBoolean([application t:'Finder'])
        begin
            key_eq('f');
            if await_presence([application t:'Find File'], kAwaitTime)
                useAppleMenu := false;
        end;

        if useAppleMenu
        begin
            if not select_menuItem('Find File', 1)
            begin
                RError('FindFile: Target has no Find File DA installed...',v_level);
                return false;
            end;

            if not await_presence([application t:'Find File'], kAwaitTime)
            begin
                RError('FindFile: Find File menu item selected, DA did not come to the front...',v_level);
                return false;
            end;
        end;
    end;


    # MAKE SURE FIND FILE WINDOW IS IN FRONT WITH ONLY ONE LINE OF CHOICES

    key_eq('f');    # Activates Find File window if Items Found window was in front.
    await_presence([window t:/Find File≈/ o:1], kAwaitTime);

    while _MatchBoolean([button t:'Fewer Choices' w:1])
    begin
        saveSpeed := typeSpeed(10);
        key_eq('rrrrrrrrrrr');
        typeSpeed(saveSpeed);
    end;


    # SET ALL NECESSARY PARAMETERS IN FIND FILE DIALOG BOX

    currentWindow := _Match([window o:1]);
    windRect := currentWindow.r;
    volValue := currentWindow.k[3].s[1];
    if volValue  <> 1
    begin
        maxVolValue := currentWindow.k[3].s[2];
        shiftFindFileWindowY := maxVolValue * kPopUpDisplacement + kXYOffset;
        if windRect[2] < shiftFindFileWindowY                        # if needed, relocate Find File window
        begin
            move_mouse({'absolute',{windRect[1],windRect[2]},'down',{windRect[1],shiftFindFileWindowY},
                        'wait1','up'});
            currentWindow := _Match([window o:1]);
            windRect := currentWindow.r;
        end;
        initXCoord := windRect[1] + kSearchVolXCoord;
        initYCoord := windRect[2] + kSearchVolYCoord;
        finalYCoord := windRect[2] + (kSearchVolYCoord - (kPopUpDisplacement * (volValue - 1)));
        move_mouse({'absolute',{initXCoord,initYCoord},'down',{initXCoord,finalYCoord},'wait1','up'});
    end;
    if pSearchBy  <> 'name'
    begin
        initXCoord := windRect[1] + kSearchByXCoord;
        initYCoord := windRect[2] + kSearchByYCoord;
        finalYCoord := windRect[2] + kSearchByYCoord + kPopUpDisplacement * searchByOffset;
        move_mouse({'absolute',{initXCoord,initYCoord},'down',{initXCoord,finalYCoord},'wait1','up'});
    end;
    if pSearchConstraint  <> 'contains'
    begin
        initXCoord := windRect[1] + kSearchByXCoord * kConstraintRegionOffset;
        initYCoord := windRect[2] + kSearchByYCoord;
        finalYCoord := windRect[2] + kSearchByYCoord + kPopUpDisplacement * searchConstraintOffset;
        move_mouse({'absolute',{initXCoord,initYCoord},'down',{initXCoord,finalYCoord},'wait1','up'});
    end;

    initXCoord := windRect[1] + kSearchByXCoord * kArgumentRegionOffset;
    initYCoord := windRect[2] + kSearchByYCoord;
    if pSearchBy = 'kind'                                        # if pSearchBy 'kind'
    begin
        _PressMouse();
        finalYCoord := windRect[2] + kSearchByYCoord + kPopUpDisplacement * searchArgumentOffset;
        move_mouse({'absolute',{initXCoord,initYCoord},'down',{initXCoord,finalYCoord},'wait1','up'});
    end;
    else                                                        # i.e., if pSearchBy 'name' or 'version'
    begin
        move_mouse({'absolute',{initXCoord,initYCoord},'click'});
        type_keys({'latch',commandKey,'a',pSearchArgument});
    end;

    # EXECUTE SEARCH

    type_keys({returnKey});
    if  (await_absence([window t:/Find File≈/ o:1], kAwaitTime))
    begin
        if _MatchBoolean([staticText t:'No items were found.' w:[window t:'' o:1 s:dialog]])
        begin
            select_descriptor([button t:'OK']);
            key_eq('q');
            RError("FindFile: {pSearchArgument} not found on the selected volume(s).",v_level);
            return false;
        end;
    end;


    # LOCATE THE ITEM FOUND

    currentWindow := _Match([window o:1]);
    if not (currentWindow.t = 'Items Found')
    begin
        RError("FindFile: 'Items Found' window not active...",v_level);
        return false;
    end;
    itemsFoundWindowRect := currentWindow.r;
    if (card pSearchArgument) > kMaxArgumentLength
    begin
        searchArgumentLength := (card pSearchArgument);
        subArgumentBaseIndex := searchArgumentLength - kMaxArgumentLength +1;
        searchSubArgument := pSearchArgument[subArgumentBaseIndex];
        for i := (subArgumentBaseIndex + 1) to searchArgumentLength
        begin
            searchSubArgument := searchSubArgument + pSearchArgument[i];
        end;
        _Match([screen]);
        positionFound := LocateString(searchSubArgument,locateStringWindowRect,'Geneva',9);
    end;
    else
    begin
        _Match([screen]);
        positionFound := LocateString(pSearchArgument,locateStringWindowRect,'Geneva',9);
    end;
    if  not positionFound
    begin
        RError("FindFile: Could not locate {pSearchArgument} in ∂'Items Found∂' window...",v_level);
        return false;
    end;


    # PERFORM THE ACTION REQUESTED

    switch pActionWhenFound
    begin
        case 'launch':
        begin
            move_mouse({'absolute',{positionFound[1], positionFound[2]}});
            _PressKey({optionKey});
            _DoubleClick();

            ### Must wait a short time with option key down, but too long will
            ### carry into the app launch - many apps will act differently and fail.
            ### Wait(1) fails with one target (too long).
            wait(0,0,0,60);
            _ReleaseKey({optionKey});

            if  (await_absence([application t:/Find File≈/ ], kAwaitTime))
            begin
                RStatus("{pSearchArgument} found and launched >>>",v_level);
                return true;
            end;
            else
            begin
                select_descriptor([button t:'OK']);
                key_eq('q');
                RError("FindFile: Could not launch {pSearchArgument}...",v_level);
                return false;
            end;
        end;
        case 'open':
        begin
            move_mouse({'absolute',{positionFound[1],positionFound[2]}});
            _Click();
            key_eq('o');
            if (await_absence([window t:/Find File≈/ o:1], kAwaitTime))
            begin
                RStatus("{pSearchArgument} found and opened >>>",v_level);
                return true;
            end;
            else
            begin
                RError("FindFile: Could not open {pSearchArgument}...",v_level);
                return false;
            end;
        end;
        case 'open folder':
        begin
            move_mouse({'absolute',{positionFound[1],positionFound[2]}});
            _Click();
            key_eq('e');
            if (await_absence([window t:/Find File≈/ o:1], kAwaitTime))
            begin
                RStatus("Enclosing folder for {pSearchArgument} has been opened >>>",v_level);
                return true;
            end;
            else
            begin
                RError("FindFile: Could not open {pSearchArgument}∂'s enclosing folder...",v_level);
                return false;
            end;
        end;
        default:
        begin
            RError("FindFile: Action to perform after finding {pSearchArgument} is invalid...",v_level);
            return false;
        end;
    end;

end;


#########################################################################
#    task    find(searchText, expectedKind, constraint, searchBy, searchLocation, allAtOnce, v_level)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Find a file in the System 7 Finder using the find command.
#                    The file type is needed to ensure the right type of file
#                    is found.  For example, if an application is desired, it
#                    shouldn't select a document which happens to have the same
#                    name.  If a find is successful, the file will be selected
#                    upon return of this task.
#    Parameters:        searchText:        Text to search on.  This value changes
#                                    depending on the searchBy parameter.  For
#                                    example, when searching by size, searchText
#                                    will be a number in Kbytes.
#                    expectedKind:    What type of file is expected to be found.
#                                    A value of "" means no kind matching is desired.
#                                    Possible types are:
#                                        appsysfile (includes DAs, control panels,
#                                            extensions of all kind, suitcases, files,
#                                            fonts, sounds, keyboard layouts, & scripts),
#                                        folder (includes disks),
#                                        document (includes stationery),
#                                        alias
#                    constraint:        Searching constraints.  This value changes depending
#                                    on the searchBy parameter.  For the different searchBy
#                                    values, possible values are:
#                                        name:    contains, doesn't contain, starts with,
#                                                ends with, is, is not
#                                        size:    is less than, is greater than
#                                        kind:    contains, doesn't contain
#                                        version:is, is before, is after, is not
#                                        comments:contain, do not contain
#                    searchBy:        What attribute of the file to search by.  Possible values are:
#                                        name (default)
#                                        size
#                                        kind
#                                        version
#                                        comments
#                    searchLocation:    Where to perform search. Possible values are:
#                                        0 - On all disks (default)
#                                        1 - On the boot drive
#                                        8 - Inside the current window
#                                        9 - The selected items
#                                            - or -
#                                        string - volume name to search a particular volume
#                                            - or -
#                                        list - possible enclosing window names (check AFTER the find)
#                    allAtOnce:        Will find everything at once if true.  Default is false.
#                                    If this option is selected, then expected kind matching
#                                    is turned off.
#                    v_level:        verbosity level for log output
#    Returns:        true -     an error occured
#                    false - found file
#    Examples:        Find("MPW Shell","appsysfile","is","name",1);   # Search for the application 'MPW Shell' on the boot disk
#                    Find("RoboSport","folder","is",,0);                # Search for folder 'RoboSport' on all disks
#                    Find("folder","",'contains','kind');            # Search for a folder
#                    Find("5","",'is less than','size');                # Search for any type of file less than 5k
#                    Find("Monitors","appsysfile",'is','name',8);    # Search for Monitors CDEV inside the current window
#    Assumptions:    VU 2.0.1
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        7/26/91 EH        Creation as part of FinderLib.vu for 007.
#        3/23/92    Jason Marsh        Incorporated into Clouseau.lib.
#        06/02/93    SBR        Changed default parameters to use quick Find (Fewer Choices)
#        06/02/93    SBR        Search for bogus item only if needed to save time
#        06/02/93    SBR        Added ordinals for popups, increased typeSpeed
#        06/17/93    SBR        Removed unnecessary matches for expectedKind check
#        06/17/93    SBR        Can pass list of possible enclosing windows in searchLocation
#        11/29/93    SBR        Added await_presence for Get Info Window
#        11/29/93    SBR        Increased await_ timeout values in most places for VM stress
#        01/29/94    SBR        Added multiple item wait loop for candy stripe dialog
#        03/07/94    GTK        Changed popup ordinals. NOTE: This change is a hack which will
#                            work only if the search is reset. (i.e. When the bogus item is
#                            found.) Before this change ordinals weren't working at all anyway.
#                            This task needs a major rework, so use with caution until then.
#        05/25/94    SBR        Modified to use _matchBoolean where appropriate
#        07/06/94    SBR        Reduced await_absence time for 'Stop' button from 32767 to 32706
#                            to avoid VU 2.0.1 overflow error (32767 max integer value).
#        07/07/94    SBR        Use cmd-shift-f (or g) to use (or reuse) System 7.0 Find and avoid
#                            System 7.5 Find File DA, which is different and not scripted yet.
#                            The shift key should be ignored in stock pre-7.5 systems.
#        09/27/94    SBR        Await_absence [staticText] after the bogus find to avoid skipping
#                            the shift key on slow Macs.
#        08/08/95    SBR        Added pathName comparison for Radar 1275447
#        09/27/96      BRL/MSO    Added SPEC exception handling
#########################################################################
task    find(searchText, expectedKind := "", constraint := "", searchBy := "",
                        searchLocation := false,allAtOnce := false, v_level:= 5)
begin
    global gPreviousFinderFindString;

    RStatus("begining Find routine for {searchText}",v_level);
    # variables for return values
    complete := true;         # result code RETURNED if tool could be completely run
    incomplete := false;     # result code RETURNED if tool could not be completely run
    status := complete;        # result code to be returned by this task
    found := true;
    couldntFind := false;
    prevInfoWindow := [];
    prevWindowPath := '';

    if (searchText = "")
        return incomplete;

    searchLocationType := typeOf(searchLocation);

    #### Turn expected kind matching off if allAtOnce is true because there may be more than one
    if (allAtOnce)
        expectedKind := "";

    #### Go to Finder
    if not _MatchBoolean([application t:"Finder"])            #RIncomplete always returns false
        if not twitch("Finder")
            return RIncomplete("find: Could not make Finder active.");

    #### Store the existing windows for later (see Radar 1275447)
    try
        match [window t:$oldWindowNames r:$oldWindowRects];
    catch theError
        ExceptionDispatcher(theError,,{"match 1 in find", {searchText, expectedKind, constraint, searchBy,
                        searchLocation, allAtOnce, v_level}});

    #### Get 7.0 Find window to front
#    key_eq('F',,6);                    # use cmd-shift-f to use 7.0 Find, not 7.5 Find File DA
#    if (await_presence([window t:"Find" o:1 g:false z:false c:false],60,,true,6) = error)
    if not use_7_0_find( false )
        return RIncomplete("find: Find window did not come to front");

    ## Select Fewer Choices so that the search parameters are reset

    if _Match([window o:1]).k[3].t <> 'More Choices'
    begin
        select_descriptor([button t:'Fewer Choices'], v_level);
        if (await_presence([button t:'More Choices'],60) = error)
        begin
            _Type({ escapekey });
            return incomplete;
        end;
    end;

    #### Find a bogus item - This is to compensate for a 7.0-7.1 Find bug
    #### SBR:     Do this only if the current Find item is the same as the
    ####         previous item, or if the previous item is unknown.
    if searchText = gPreviousFinderFindString or isUndefined(gPreviousFinderFindString)
    begin
        saveSpeed := typeSpeed(50);

        _Type({ "Gobblygook! - sdjhfsd", returnKey });
        typeSpeed(saveSpeed);
        if (await_presence([staticText t:'No matching items were found.'],300) = error)
        begin
            _Type({ escapekey });
            return incomplete;
        end;
        else
        begin
            # 09/27/94 SBR: await_absence to avoid skipping the next shift key on slow Macs

            _Type({ returnKey });
            await_absence([staticText t:'No matching items were found.'],300);
        end;

        #### Get 7.0 Find window to front again
#        key_eq('F',,5);                    # use cmd-shift-f to use 7.0 Find, not 7.5 Find File DA
#        if (await_presence([window t:"Find" o:1 g:false z:false c:false],60,,true,6) = error )
        if not use_7_0_find( false )
            return RIncomplete("find: Find window did not come to front the second time");
    end;

    #### Open More choices window if not a generic search
    if (constraint or searchBy or (searchLocation <> false) or allAtOnce) and
            searchLocationType <> 'list'
        if _MatchBoolean([button t:"More Choices"])
            select_descriptor([button t:"More Choices"], v_level);

    #### Set parameters
    if _MatchBoolean([button t:"Fewer Choices"])
    begin
        ## search by
        if (select_descriptor([menuItem t:searchBy m:[popup e:true o:7 w:1]], v_level) = error)
        begin
            _Type({ escapeKey });
            return incomplete;
        end;

        ## constraints
        #### GTK: Changed popup ordinal
        #if (select_descriptor([menuItem t:constraint m:[popup e:true o:1 w:1]]) = error)
        if (select_descriptor([menuItem t:constraint m:[popup e:true o:6 w:1]]) = error)
        begin
            _Type({ escapeKey });
            return incomplete;
        end;

        ## search location (integer)
        #### GTK: Changed popup ordinal
        #searchLocMenu := [popup o:6 w:1]!;
        searchLocMenu := [popup o:5 w:1]!;
        if searchLocationType = 'integer'
        begin
            if (searchLocation = 0)
                select_descriptor([menuitem o:1 m:searchLocMenu]);
            else if (searchLocation = 1)
            begin
                if _MatchBoolean([menuitem t:'on all disks' m:searchLocMenu])
                    select_descriptor([menuitem o:3 m:searchLocMenu]);
                else
                    select_descriptor([menuitem o:1 m:searchLocMenu]);
            end;
            else if (searchLocation = 8)
                select_descriptor([menuitem t:/inside≈/ m:searchLocMenu]);
            else if (searchLocation = 9)
                select_descriptor([menuitem t:/≈selected≈/ m:searchLocMenu]);
        end;
        else if searchLocationType = 'string'
            select_descriptor([menuitem t:"on “{searchLocation}”" m:searchLocMenu]);

        ## all at once
        try
            match [checkbox t:"all at once" s:?set];
        catch theError
            ExceptionDispatcher(theError,,{"match 2 in find", {searchText, expectedKind, constraint, searchBy,
                        searchLocation, allAtOnce, v_level}});

        if ((set[1] = 0 and allAtOnce) or (set[1] = 1 and not allAtOnce))
            select_descriptor([checkbox t:'all at once']);
    end;

    #### Type in name and go
    saveSpeed := typeSpeed(50);

    _Type({ searchText, returnKey });
    typeSpeed(saveSpeed);

    gPreviousFinderFindString := searchText;        # save for next find

    ####
    done := false;
    while not (done)
    begin
        #### Wait 30 seconds until the candy stripe dialog OR one of the possible
        #### enclosing windows is in the front. If the candy stripe appears, wait
        #### "forever" for it to go away. Added 01/29/94 SBR.

        previousTime := _Match ([time]);

        secondsLeft := 30;
        lookForEnclosingWindow := typeOf(searchLocation) = 'list';

        while secondsLeft > 0
        begin
            if _MatchBoolean([button t:'Stop' o:1 w:'Find' o:1])
            begin
                await_absence([button t:'Stop' w:[window t:'Find' o:1]],32706,,true,6);
                secondsLeft := 0;
            end;

            else if lookForEnclosingWindow
            begin
                if isMember(_Match([window o:1], true).t, searchLocation)
                begin
                    secondsLeft := 0;
                end;
            end;

            if secondsLeft
            begin
                secondsLeft := secondsLeft - time_sub(previousTime, _Match ([time]))[1];
            end;
        end;

        #### Wait for dialogs

        if _MatchBoolean([staticText t:'No matching items were found.' w:[window s:dialog o:1]])
        begin
            select_descriptor([button t:'OK']);
            return couldntFind;
        end;

        else if _MatchBoolean([staticText t:/≈was found on the desktop./ w:[window s:dialog o:1]])
            select_descriptor([button t:'OK']);

        key_eq('i',, v_level);                                    # Look at the Get Info window
        await_presence([window t:/≈ Info≈/ o:1],60,,true,6);    # wait before matching

        infoWindow := _Match([window o:1], true);
        key_eq('w',, v_level);

        #### Have we found the same file, if so check the path, we may be done.
        #### Added pathName comparison for Radar 1275447.
        if ((prevInfoWindow.r = infoWindow.r) and            # NOTE: Here we cannot use
                (prevInfoWindow.t = infoWindow.t) and        # "prevInfoWindow = infoWindow"
                (prevInfoWindow.k = infoWindow.k))            # because of a bug in VU equality
        begin
            try
                match [window t:?windowName r:?windowRect o:1]!;
            catch theError
                ExceptionDispatcher(theError,,{"match 3 in Find", {searchText, expectedKind, constraint, searchBy,
                        searchLocation, allAtOnce, v_level}});

            curWindowPath := '';

            while (windowName <> 'Desktop')
            begin
                curWindowPath := windowName + ':' + curWindowPath;
                tNameIndex := isMember(windowName, oldWindowNames);
                tRectIndex := isMember(windowRect, oldWindowRects);

                if (not tNameIndex) OR (not tRectIndex) OR (tNameIndex <> tRectIndex)
                    _PressKey({optionKey});
                type_keys({'latch', commandKey, upArrowKey});
                _ReleaseKey({optionKey});
                await_absence([window t:windowName o:1]);

                try
                    match [window t:?windowName r:?windowRect o:1]!;
                catch theError
                    ExceptionDispatcher(theError,,{"match in Find loop", {searchText, expectedKind, constraint, searchBy,
                        searchLocation, allAtOnce, v_level}});
            end;
            if prevWindowPath = curWindowPath
                return couldntFind;
        end;

        if (infoWindow.t = 'Find')        # This is for a special case when trying to find the trash.
        begin                            # The 'couldn't find…' dialog doesn't come up.
            _Type({ escapeKey });
            return couldntFind;
        end;

        done := true;                    # Get ready for last few qualifications

        #### Check expected kind
        if (expectedKind)
        begin
            locked := infoWindow.k[1] ~= [checkbox t:'Locked'];
            stationery := infoWindow.k[1] ~= [checkbox t:'Stationery pad'];
            findOriginal := infoWindow.k[1] ~= [checkbox t:'Find Original'];

            #### Determine what kind of file it is
            if (findOriginal)
                kind := 'alias';
            else if (stationery)
                kind := 'document';
            else if (locked)
                kind := 'appsysfile';
            else kind := 'folder';

            if not (expectedKind = kind)
                done := false;
        end;

        if (searchBy = 'name') and done                    # If we are searching by name, then
            if not (infoWindow.t ~= /≈{searchText}≈/)    # check the name of the info window.
                done := false;
        if searchLocationType = 'list' and done
        begin
            enclosingWindow := _Match([window o:1]);
            for each enclosingWindowName in searchLocation
            begin
                if enclosingWindowName = enclosingWindow.t
                    return found;
            end;
        end;
        if not done
        begin
            prevInfoWindow := infoWindow;                # We are not done, so try again.
#            key_eq('G',,6);            # use cmd-shift-g to re-use 7.0 Find, not 7.5 Find File DA
            use_7_0_find(true);        # use cmd-shift-g to re-use 7.0 Find, not 7.5 Find File DA
        end;
    end;

    return found;
end;

#########################################################################
#    task                    use_7_0_find( pRetry )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Get the 7.0 find window open. Normally this would only require a
#                    cmd-shift-f, but there is a bug (1221761) where the shift key is
#                    ignored occasionally, bringing up the 7.5 Find File app instead.
#                    This task will quit Find File and retry until it succeeds.
#    Parameters:        pRetry:    Boolean to specify if this is a retry or not
#    Returns:        true or false indicating success or failure (false is very bad!)
#    Examples:        use_7_0_find( false );        instead of cmd-shift-f
#                    use_7_0_find( true );        instead of cmd-shift-g
#    Assumptions:    Finder in front, nothing to prevent the Find window from opening
#                    (besides the 7.5 Find File app as described)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        02/20/95    SBR        Created
#        06/01/96    MSO        Changed to use key_eq modifier 6 to improve chances of getting the 7.0 find
#        09/27/96      BRL/MSO    Added SPEC exception handling
#########################################################################
task    use_7_0_find( pRetry := false )
begin
    done := false;

    if not pRetry                    # start a new Find
    begin
        while true
        begin
            wait(1);
            key_eq('f',6,6);    # use cmd-shift(modifier 6)-f to use 7.0 Find, not 7.5 Find File app
            tEndTime := get_end_time(60);        # wait 60 seconds maximum for 7.0 Find window

            while not _MatchBoolean([application t:'Find File'])
            begin
                if timed_out(tEndTime)
                    return false;

                if _MatchBoolean( [window t:"Find" o:1 g:false z:false c:false])
                    return true;
            end;

            # the 7.5 Find File app came to the front, so quit and retry
            key_eq('q');

            while not _MatchBoolean([application t:'Finder']);
            wait(3);                # waiting makes it work more reliably
        end;
    end;
    else                            # repeat the last Find
    begin
        while true
        begin
            wait(1);
            key_eq('G',,6);            # use cmd-shift-g to repeat 7.0 Find, not 7.5 Find File app
            tEndTime := get_end_time(5);        # wait 5 seconds maximum for Find File app

            while not _MatchBoolean([application t:'Find File'])
            begin
                if timed_out(tEndTime)
                    return true;
            end;

            # the 7.5 Find File app came to the front, so quit and retry
            key_eq('q');

            while not _MatchBoolean([application t:'Finder']);
            wait(3);                # waiting makes it work more reliably
        end;
    end;
end;


#########################################################################
#    task                    abort_script(theReason)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Abort the current script cleanly, maintaining proper
#                    log format.
#    Parameters:        theReason:    string decribing the reason
#    Returns:        Nothing
#    Examples:        abort_script('the world ended');
#    Assumptions:    None
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        ???        ???        Created
#    09/03/94    SBR        Added theReason parameter
#########################################################################
task    abort_script(theReason := 'unknown reason')
begin
    RStatus("AN ERROR OCCURED WHICH IS CONSIDERED FATAL:",1);
    RStatus(theReason,1);
    RStatus("EXITING SCRIPT…",1);

    if isUndefined(global r_test_stack)
            r_test_stack := {};

    for each item in r_test_stack
        rCloseTest();
    exit;
end;


#########################################################################
#    task    AwaitText( pTextSearchInfo, time_limit := 10, persistence := 0,
#                        v_level := 4 )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Uses LocateText() to find text on the screen, within
#                    a given time limit, and persisting for a given
#                    time period, just like await_presence().
#    Parameters:        pTextSearchInfo:    A list describing text to locate:
#                        { pText, [pSearchRect, pTextOptions] }
#                        pText:    String to locate (case sensitive).
#                        pSearchRect:    Global rectangle to search in.
#                                        Use undefined for entire screen.
#                        pTextOptions:    Parameters for LocateString().
#                                        See SetTextOptions() for details.
#                    time_limit:        how long to wait in seconds
#                    persistence:    how long to ensure that the object
#                                    stays around.
#                    v_level:        verbosity level for log output
#                                    Pass a v_level of 6 to silence errors
#                                    and not have them add up for the test summary
#    Returns:        rectangle of text if found, undefined if not found
#    Examples:        AwaitText( "Start" );
#                    AwaitText( { "Stop", {20,30,400,420} },120 );
#                    AwaitText( { "Pause", undefined,
#                                {{"Chicago",12},{"Truth",12}} }, 120,10,3 );
#    Assumptions:    VU 2.1.1b1 or later ('anyColor' symbol required)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/12/97    SBR        Created
#########################################################################
task AwaitText( pTextSearchInfo, time_limit := 10,
                    persistence := 0, v_level := 4 )
begin
    wait_end := get_end_time(time_limit);    # Reset the time limit timer
    persist_end := 0;                        # Reset the persistence timer

#        if pTextOptions
#            pTextOptions := ValidateTextOptions(pTextOptions);
#
#        # If not valid, pTextOptions will be undefined.
#        if isUndefined( pTextOptions )
#        begin
#            RError("AwaitText: invalid pTextOptions: {pTextOptions}.");
#            return undefined;
#        end;

    while true
    begin
        found := LocateText( pTextSearchInfo );
        if not found
            persist_end := 0;                # No match; reset persistence
        else
        begin
            if not persistence
                return found;
            else
            begin
                if not persist_end
                    persist_end := get_end_time(persistence);
                if timed_out(persist_end)
                    return found;
            end;
        end;

        if timed_out(wait_end)
        begin
            if not pTextOptions
                pTextOptions := GetTextOptions();

            RIncomplete("AwaitText: Text did not appear, time limit = {time_limit}",v_level);
            RStatus("∂t∂tText = '{pTextSearchInfo[1]}', Rect = {pTextSearchInfo[2]}, " +
                        "Options = {pTextSearchInfo[3]}", v_level);
            RDumpState(,v_level);
            return undefined;
        end;

        wait(0,0,0,500);    # Don't drown the target in LocateString calls.
    end;
end;


#########################################################################
#    task                LocateText( pTextSearchInfo )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Uses LocateString to find text on the screen. You can
#                    pass in text options, or call the SetTextOptions()
#                    task first. A single call to LocateText can iterate
#                    over several fonts, sizes, styles and colors.
#    Parameters:        pTextSearchInfo:    A list describing text to locate:
#                        { pText, [pSearchRect, pTextOptions] }
#                        pText:    String to locate (case sensitive).
#                        pSearchRect:    Global rectangle to search in.
#                                        Use undefined for entire screen.
#                        pTextOptions:    Parameters for LocateString().
#                                        See SetTextOptions() for details.
#    Returns:        rectangle of text if found, undefined if not found
#    Examples:        LocateText( "Start" );
#                    LocateText( { "Stop", {20,30,400,420} } );
#                    LocateText( { "Pause", undefined,
#                                    {{"Chicago",12},{"Truth",12}} } );
#    Assumptions:    VU 2.1.1b1 or later ('anyColor' symbol required)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/12/97    SBR        Created
#########################################################################
task LocateText( pTextSearchInfo )
begin
    if TypeOf(pTextSearchInfo) <> 'list'
        pTextSearchInfo := {pTextSearchInfo, undefined, {}};
    else
    begin
        switch card pTextSearchInfo
        begin
            case 1:
                pTextSearchInfo := pTextSearchInfo + {undefined, {}};
            case 2:
                pTextSearchInfo := pTextSearchInfo + {{}};
            case 3:
                ;    #do nothing if it's full
            default:
            begin
                # Either 0 or more than 3, all invalid.
                RError("LocateText: invalid pTextSearchInfo: {pTextSearchInfo}.");
                return undefined;
            end;
        end;
    end;

    pText := pTextSearchInfo[1];
    pSearchRect := pTextSearchInfo[2];
    pTextOptions := pTextSearchInfo[3];

    if pTextOptions
    begin
        # Fill them out with default options if necessary.
        pTextOptions := ValidateTextOptions( pTextOptions );
    end;
    else
    begin
        # Or, get the global value stored previously with SetTextOptions.
        pTextOptions := GetTextOptions();
    end;

    # If either fails, pTextOptions is undefined.
    if isUndefined( pTextOptions )
    begin
        RError("LocateText: Call SetTextOptions() first, or use the pTextOptions parameter.");
        return {};
    end;

    # Using each text option in turn, try to locate the string.
    numTexts := card pTextOptions;
    for i := 1 to numTexts
    begin
        tOptions := pTextOptions[i];
        tRect := LocateString(pText, pSearchRect, tOptions[1], tOptions[2], tOptions[3],
                                tOptions[4], tOptions[5]);
        if not isUndefined(tRect)
            i := 99999;
        else if i = numTexts
            tRect := {};
    end;

    return tRect;
end;


#########################################################################
#    task                SetTextOptions( pTextOptions )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Call this to set up text options that you intend to
#                    use often, so you don't have to pass them into the
#                    LocateText() task every time.
#    Parameters:        pTextOptions: Valid parameters for LocateString().
#                        { pList1, ... , pListN }
#                        pListN := { font,size }  OR
#                        pListN := { font,size,style }  OR
#                        pListN := { font,size,style,textColor }  OR
#                        pListN := { font,size,style,textColor,bgColor }
#    Returns:        true if successful, false if there was an error
#    Examples:        instead of using:
#                        LocateText( { "Pause", undefined,
#                                        {{"Chicago",12},{"Truth",12}} } );
#                        LocateText( { "Stop", undefined,
#                                        {{"Chicago",12},{"Truth",12}} } );
#                    you can use:
#                        SetTextOptions( {{"Chicago",12},{"Truth",12}} );
#                        LocateText( { "Pause", undefined } );
#                        LocateText( { "Stop", undefined } );
#    Assumptions:    VU 2.1.1b1 or later ('anyColor' symbol required)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/12/97    SBR        Created
#########################################################################
task SetTextOptions( pTextOptions )
begin
    global gTextOptions;

    gTextOptions := ValidateTextOptions( pTextOptions );
    returnValue := not not gTextOptions;

    if returnValue
    begin
        RStatus("SetTextOptions: gTextOptions := {gTextOptions}",5);
    end;
    else
    begin
        RError("SetTextOptions: pTextOptions := {pTextOptions}");
    end;

    return returnValue;
end;


#########################################################################
#    task                GetTextOptions( )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Used internally by the LocateText() task.
#                    Returns the validated text options that were set by
#                    the SetTextOptions() task.
#    Parameters:        none
#    Returns:        Global text options, or undefined if not set yet.
#    Examples:        curTextOptions := GetTextOptions();
#    Assumptions:    value was previously set
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/12/97    SBR        Created
#########################################################################
task GetTextOptions( )
begin
    return global gTextOptions;
end;


#########################################################################
#    task                ValidateTextOptions( pTextOptions )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Used internally by LocateText() and SetTextOptions().
#                    Validates and populates a test options list.
#    Parameters:        pTextOptions: Valid parameters for LocateString().
#                        { pList1, ... , pListN }
#                        pListN := { font,size }  OR
#                        pListN := { font,size,style }  OR
#                        pListN := { font,size,style,textColor }  OR
#                        pListN := { font,size,style,textColor,bgColor }
#    Returns:        pTextOptions, validated and fully populated
#    Examples:        ValidateTextOptions( {{"Chicago",12},{"Truth",14,1}} );
#                    This would return:
#                        {    { "Chicago", 12, 0, anyGolor, anyColor },
#                            { "Truth", 14, 1, anyGolor, anyColor }    }
#    Assumptions:    VU 2.1.1b1 or later ('anyColor' symbol required)
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        03/12/97    SBR        Created
#########################################################################
task ValidateTextOptions( pTextOptions )
begin
    # Turn it into a list of lists if not already.
    if typeOf(pTextOptions[1]) <> 'list'
        pTextOptions := {pTextOptions};

    # Add defaults to fully specify each text option (font and size required).
    numTexts := card pTextOptions;
    for i := 1 to numTexts
    begin
        switch card pTextOptions[i]
        begin
            case 2:
            begin
                # Default to plain style, any text or background color.
                pTextOptions[i] := pTextOptions[i] + {0, anyColor, anyColor};
            end;

            case 3:
            begin
                # Default to any text or background color.
                pTextOptions[i] := pTextOptions[i] + {anyColor, anyColor};
            end;

            case 4:
            begin
                # Default to any background color.
                pTextOptions[i] := pTextOptions[i] + {anyColor};
            end;

            case 5:
            begin
                # Fully specified, don't do anything.
            end;

            default:
            begin
                # Either 0, 1, or more than 5, all invalid.
                RError("ValidateTextOptions: invalid text options in {pTextOptions[i]}.");
                pTextOptions := undefined;
                i := 99999;
            end;
        end;
    end;

    RStatus("ValidateTextOptions: {pTextOptions}",5);
    return pTextOptions;
end;